FDATEBEG.DOC    --   A "quick start" introduction to using Fdate
======================================================================
Revision date: 1996 Feb 1

"Everything you'd ever want to do with dates in batch files"

INTRODUCTION: WHAT IS FDATE?
============================
Fdate is a utility for doing date formatting and date arithmetic in DOS
batch files.  There are a number of different ways to put FDATE's output
into environment variables.  Once this has been done, the environment
variables can be used and manipulated in many ways in the batch file.

FDATE is freeware, or what is technically known as "zero-cost shareware". 
There is no requirement to register FDATE in any way.  For more details,
see the DISTRIBUTION ISSUES section in the FDATE.DOC file.

Here are some of the things you can do with FDATE.

    accept user input from the keyboard

    retrieve today's date in a variety of formats
      place today's date into a file name

    reformat dates 
       Output formats include common American and European formats, or you
       can "roll your own" by manipulating environment variables.  Month
       and weekday names can be produced in several languages (English,
       French, German, Spanish).

    calculate the dates of holidays in a given year

    do date arithmetic
      determine the date N days before/after a given date
      compare two dates to determine which is earlier
      compare two dates to determine how many days apart they are

    determine if a year is a leap year
    determine whether a year is evenly divisible by some number

    determine what day of the week a date falls on
      run certain software only on certain days of the week

    retrieve the date/time from the date/timestamp of a file
    do simple integer arithmetic (add, subtract, modulus)
    calculate the time a piece of software takes to run
    convert a calendar date to/from a "business julian" date

    extract a substring from an environment variable
    right, left, or center justify a string

Fdate's original purpose was to do date formatting and date arithmetic in
DOS batch files.  Over the years, functions were added to Fdate to support
activities that people often need to do in conjunction with working with
dates (simple arithmetic and string manipulation, for instance).  As Fdate
grew, the documentation grew also.  Fdate's documentation file, FDATE.DOC,
is now quite large and rather intimidating.  Some new users have reported
having a hard time using FDATE.DOC to learn how to use FDATE do the basic
tasks that they need to do with dates. 

To help you get started using Fdate, I've created this short file called
FDATEBEG.DOC (FDATE beginners documentation), which shows how to use Fdate
to do the things most users want to do.  If you're using Fdate for the
first time, I suggest that you start by reading this.  

When you've finished, you may still have a question: "Can I do such-and-
such with Fdate?"  If it involves dates, it can probably be done with
Fdate, although tricky things are of course tricky to do, even with Fdate.  
A good next step would be to look at the list of examples in FDATE.DOC. 
With luck, you will find Fdate doing such-and-such in one of the examples. 
To understand how Fdate is working in a particular example, use the
"language reference manual" part of the FDATE.DOC to look up the parameters
used in the example.

When all else fails, reading the documentation often proves useful.

   Good Luck! 
   Steve Ferg

THE 3-MINUTE INTRODUCTION TO FDATE
==================================

By far the most popular use of Fdate is to put today's date-- in a
particular format-- into an environment variable.  Once this has been done,
the environment variable can be used and manipulated in many ways in a
batch file.  Here are a few short exercises that will help you to learn how
to use Fdate's most basic features to do that.


1.
At the DOS prompt, type:  
  
       FDATE
 
  This will show you Fdate's HELP screens.  Press ENTER to page through
  the HELP screens.

  The information on these HELP screens is very dense.  It won't teach you
  how to use Fdate, but it is useful for jogging your memory as you become
  familiar with Fdate's various features.

2.
At the DOS prompt, type:  

       FDATE /Ff

  I've used lowercase "f" here to distinguish the value of the parameter
  from the parameter-letter itself, but it really doesn't matter whether
  the parameter or its value is in upper or lower case.  Except for the /K
  parameter (one of Fdate's advanced features), Fdate's parameters are not
  case sensitive.

  Here, the value of the "/F" (function) parameter is "f" (format a date). 
  The "/Ff" parameter tells Fdate that the function you want it to perform
  is to format a date.  Since the default date is "today", this command
  will cause Fdate to display today's date on your screen in Fdate's
  default output format.

3.
At the DOS prompt, type:

       FDATE /Ff /P"Today is "

  This command is just like the one in the previous example, except that
  we've specified the "prefix parameter" (/P), which tells Fdate to add a
  string to the beginning of its output.  (There is also a "suffix
  parameter" that tells Fdate to add a string to the end of its output.) 
  Note that the value of the /P parameter is enclosed in quotes.  (Either
  single quotes or double quotes will work.)  We've had to enclose the
  value in quotes because it contains embedded blanks (one blank after the
  word "today" and another after the word "is"). 

4.
At the DOS prompt, type: 

       FDATE /Ff /Occyymmdd

  (Or you can put the same statement in a batch file.)

  Here, you are telling Fdate to put out today's date in a specific
  format.  On the "output format" parm (/O) you are specifying that you
  want the day in "ccyymmdd" format: two digits each for century, year-
  within-century, month, day-of-month.

  Note that the /O parm is not free-format.  Fdate supports many (but a
  finite number) of output formats.  If you request output in (for
  example) "yyccddmm" format, Fdate will reject your request, because it
  does not support that particular output format.  Then you will have to
  "roll your own" date format (see below).

5.
At the DOS prompt, type:

       FDATE /Ff /Omm/dd/ccyy 

  Here, you are telling Fdate to put out today's date in another of its
  supported output formats, in this case "mm/dd/ccyy".


6.
At the DOS prompt, type:

       FDATE /Ff /Occyymmdd /Vdate1

  (Or you can put the same statement in a batch file.)

  Here, you are telling Fdate to put out today's date in "ccyymmdd"
  format.  Because you are specifying the "environment variable" parm (/V)
  as "date1", Fdate is not writing its output to the screen.  It is
  putting its output in an environment variable called "date1".  Now, if
  you type "SET" at the DOS prompt, and if today is February 1, 1995, you
  will see as the last line of the SET output:

            DATE1=19950201

  At this point, you know everything you need to know to put today's date
  into an environment variable, which you can then use for whatever you
  want.  Here's an example in which you are copying a file (BACKUP.LOG,
  which is put out by a backup program) to a file whose name contains
  today's date.

            FDATE /Ff /Occyymmdd /Vdate1
            copy BACKUP.LOG  %date1%.LOG

7.
  Everybody, it seems, has their own preferred, and often unique, date
  format.  Most likely, you will want the date in some format other than
  "ccyymmdd". 

  To see if Fdate supports the output format that you want, look at the
  FDATE help screens (as you did in step 1, above), or look at the
  complete documentation in FDATE.DOC.

  If you find that Fdate does not support the precise date format that you
  want, you can "roll your own" by putting one component of the date into
  an environment variable, and then using the /P (prefix) facility to
  concatenate it onto the front of another component of the date.  Using
  this technique, you can build up virtually any date format you might
  want.  Here is an example.  You can copy it into a batch file and see
  that it actually does what it is supposed to do.

     @echo off
     :: create a date in custom format: yy-mn3-dd
     :: note the use of temporary work variable: r
     Fdate /Ff /Oyy           /Vr
     Fdate /Ff /Omn3 /P"%r%-" /Vr
     Fdate /Ff /Odd  /P"%r%-" /Vr
     echo Today is %r%


WHAT TO DO NEXT?
================
Now that you know the basics, you may have everything you need to know in
order to use FDATE to satisfy your basic date-handling needs.  If you need
more information, or are feeling adventurous, your next step should be to
explore the FDATE.DOC file.  It documents many more features of FDATE.  

One of the most useful parts of FDATE.DOC is the list of examples.  Browse
through the titles of the examples in the Table of Contents of FDATE.DOC,
getting a feel for what is there.  Then look at the examples themselves. 
Many are quite elaborate (which is natural, since they are there to show
you how to do Hard Stuff).  If example :47 looks interesting, use your
browser/viewer/editor find/search command to look for the string ":47" --
that should take you right to the example you're interested in.

Most of the examples are self-contained and ready-to-run -- if you copy the
text of the example into a batch file, the example code will run and do
what the title says it will do.  I suggest you try doing so with one or two
of the examples that seem most interesting to you.

After the examples, the most useful parts of FDATE.DOC are the sections
documenting Fdate's various functions (the functions that you can specify
on the function parm, /F) and its various output formats.  I suggest you
scan those sections, just to get a quick feel for what's available to you.

   Good Luck! 
   Steve Ferg